Description

Three independent layers guard against duplicate Google Drive folder creation in generate_playtime_report:

1. Redis lock — a RedisLock scoped per (root_folder_id, data_source_name) serialises workers within the same Redis instance (i.e. the same shard). If the lock cannot be acquired within FOLDER_LOCK_ACQUIRE_TIMEOUT (60 s), the worker logs a warning and proceeds without it (graceful degradation — no task stalling).

2. Random jitter — each task invocation sleeps random.uniform(0, FOLDER_CREATION_JITTER_MAX) (up to 10 s) once before the data-source loop. Independent shards share no Redis instance, so the lock alone cannot coordinate them; a single random offset per run spreads their arrival times across all folder levels without multiplying the delay by the number of data sources.

3. Pick-oldest — get_file passes orderBy=createdTime to files.list, so it always returns the oldest matching folder first. If two groups do race and each creates a copy, every subsequent worker converges on the same canonical (oldest) folder for all levels of the hierarchy and the file upload. Orphaned empty duplicates may exist but no files are misplaced.

Residual risk: The three layers together make the collision window very narrow but do not provide a 100% guarantee. A fully watertight fix would require a coordination mechanism shared across all shards (e.g. storing canonical folder IDs in a shared database). We have chosen to accept this low-stakes residual risk to keep the code simple: the task runs monthly, any orphaned folders are cosmetic (no data loss), and the previous behaviour created duplicates on every concurrent run.

Motivation and Context

Multiple CMs grouped in a shard all write reports to the same Google Drive root. When generate_playtime_report fires at the same scheduled time, all workers check for the folder hierarchy simultaneously. Because Google Drive allows same-named folders and its files.list API is eventually consistent, every worker sees "folder not found" and creates its own copy — producing duplicate same-named directories (e.g. multiple "BiblioBoard" folders). Different CM groups share no Redis instance, so a lock alone is insufficient.

JIRA: PP-4434

How Has This Been Tested?

• redis_fixture added to test_generate_playtime_reports so the task's Redis call resolves to a real client; FOLDER_CREATION_JITTER_MAX monkeypatched to 0 to keep the test fast.
• test_generate_playtime_report_folder_lock_contention: pre-acquires the folder lock, patches FOLDER_LOCK_ACQUIRE_TIMEOUT to 0.1 s and jitter to 0, asserts the warning is logged and the file upload still completes (graceful degradation).
• test_get_file_orders_by_created_time: verifies orderBy=createdTime is present in the Drive API request URI and that the first (oldest) result is returned when multiple exist.
• All 21 affected tests pass.

Checklist

• I have updated the documentation accordingly.
• All new and existing tests passed.